MacFormat 1997 July/macformat52.iso/mac/Shareware Plus/Games/BMAPEdit/BMAPEdit doc (text)

Text File | 1997-04-15 | 47.9 KB | 940 lines

BMAPEdit Version 3.1
(c)1993-97 Carl R. Osterwald

Introduction

BMAPEdit is a Macintosh application to create and edit maps for Bolo,
the multi-player distributed tank battle game written by Stuart
Cheshire.  BMAPEdit reads, edits, prints, and creates files (of type
'BMAP') for use with Bolo.  It has been designed to provide you, the
people who enjoy playing Bolo, with the tools needed to quickly and
efficiently make creative maps.

For more information about Bolo, the Official Bolo Home Page at:
   http://deckard.mc.duke.edu/bolo/
is highly recommended.

BMAPEdit is shareware.  If you like and use BMAPEdit, please send
$10.00 to:
    Carl R. Osterwald
    75 S. Dudley St.
    Lakewood, Colorado 80226

This program may be freely distributed provided this documentation file
is distributed also.  It may not be sold commercially.  This version is
free to individuals that have paid the shareware fee in the past.

Please send any comments, suggestions, or, most importantly,
bug reports to:
    Internet:  [e-mail]
    or by physical mail to the address above.

1.  Acknowledgments
*   Stuart Cheshire--of course, who wrote Bolo and provided the code to
      read and write Bolo map files.  Stuart also co-developed the code
      for the graphical previews that appear when opening map files.
*   Tom Barrett & Stuart Cheshire provided the Bolo preview graphics
code.
*   Scott Knaster & Keith Rollin wrote "Macintosh Programming
      Secrets," highly recommended for anyone writing Macintosh code.
*   Forrest Tanaka developed the offscreen graphics code that is
      contained in the Apple DTS Tech Note, "Principia Offscreen
Graphics".
*   Peter Lewis developed the random map generator & growth algorithms.
*   Charles Brabec granted permission to incorporate his Birdman's Map
      Maker source code as the tiled random map generator.
*   Phil Parilla developed the self-avoiding random walk-maze algorithm.
*   Jim Stout wrote the 3D buttons that are a part of Jim's CDEFs and
      available free of charge.
*   Christer Ericson wrote the function that calculates the area of a
      QuickDraw Region.
*   And especially all the beta testers whose hard work and patience
      dealing with less-than-optimum programming have allowed BMAPEdit
      to become what it is today.  Many thanks to:

    Thomas Apodaca, Aaron Bratcher, Chip Benowitz, Charles Dillon,
    Chris Hanson, Eric Hiris, Bill Ingalls, Brian Keyes, Gavin Kistner,
    Doug La Farge, Dan LaLiberte, Russell Mast, Phil Parilla,
    Caine Schneider, Andrew Tennant, & John White.

2.  System Requirements & Capabilities
*    Color Quickdraw (not available on Macs with 68000 CPUs such as
       Classics or SEs)
*    750 kBytes of memory (prefers 1 MByte)
*    System 7.0 or greater
*    Accelerated for Power Macintosh (optimized for PowerPC 604
       microprocessors)
*    Macintosh drag and drop (with System 7.5 or greater)
*    Balloon help
*    B&W printing (requires a PostScript printer)
*    Color/grayscale printing (requires a PostScript Level 2 printer)

BMAPEdit does not require a color monitor, but color will allow you to
take full advantage of the display capabilities of BMAPEdit.

Each open map window requires 66 kBytes of memory.  BMAPEdit will warn
you if the amount of free memory drops to dangerous levels as more map
windows are opened.  The amount of free memory is displayed in
BMAPEdit's About Box (choose About BMAPEdit in the Apple menu).

The amount of memory allocated to BMAPEdit affects the drawing speed.
The initial memory size is 1750 kbytes, which lets BMAPEdit use the
maximum amount of memory for its offscreen drawing buffer.  If this
memory size is reduced, drawing speeds will be somewhat slower.  In case
you need to run with less memory, you change it by quitting the
application, selecting the BMAPEdit icon (don't double-click it), and
choose Get Info… in the Finder's File menu.  You can then adjust the
memory size as your needs dictate.

BMAPEdit versions earlier than 3.0 would run under System 6.0.4 or
later.  If you are still using System 6, you should not upgrade to a
version later than 2.0.1.

Balloon help is provided for all menus, the ToolBox, and a number of
dialogs.  It can be activated from the Guide (help) menu in the right
hand side of the menu bar.  Help balloons will then appear as the mouse
is moved (after balloon help is first activated, it can take several
seconds for the balloons to start appearing).

BMAPEdit is a so-called 'fat' application, which means it contains code
to operate on either 68000 or PowerPC Macintoshes.  A modest amount of
disk space, about 200 kBytes, can be saved by removing whichever version
is not needed for your computer.  If necessary, this space can be saved
by using a utility program such as StripFat, which is available from the
popular Info-Mac FTP archive servers.

3.  Bolo Maps
Bolo maps use a grid of 256 by 256 squares.  Squares are numbered
left-to-right and top-to-bottom starting at 0 and ending at 255.  Of
these squares, the outermost 10 squares on all sides are filled with
mines by Bolo (the outer minefield) and cannot have terrain placed in
them.  Although refueling bases and pillboxes can be located in the
outer minefield, the author of Bolo discourages this and a warning
dialog box asking for confirmation is displayed when placement in the
outer minefield is attempted.  Also, Bolo does not allow any terrain
except deep water in an additional 10 square border inside of the mine
field squares.  While this deep water border is intended for start
squares (the invisible squares that define where tanks can enter the
game), bases and pillboxes may also be located here if desired.  All
regular terrain other than special squares (bases, pillboxes, and start
squares) is restricted to squares 20 through 235 horizontally, and 20
through 235 vertically.  The border of this area is called the terrain
mapping limit rectangle in BMAPEdit.

BMAPEdit does not read old-style 'resource' Bolo map files.  These older
files may be read and converted by opening them with the Bolo
application and then saving to a new file.

4.  Map Windows
The Bolo display shows the map squares in 16x16 pixel rectangles.  This
corresponds to the Preview mode in the BMAPEdit Mag menu.  Four other
modes, 12x12, 10x10, 8x8, and 5x5, display the map data in reduced Bolo
graphics.  Start squares are shown as a tank on a boat in deep water
(except for 5x5, which use a small arrow), pointed in the same direction
as the start square's direction.  Initial ownership of bases and PBs is
indicated as follows:  bases and PBs with ownership of 1 are drawn in
green (friendly); bases with ownership greater than 1 are drawn in red
(hostile) (also see the Options menu section).

The remaining display modes, 3x3 and 1x1, use single colors to represent
map terrain.  In B&W 3x3 and 1x1, land squares are black and water
squares are white.  In 1x1 magnification, an entire Bolo map can be
viewed in a window of only 256 by 256 pixels.  The colors used for the
reduced display modes have been selected to allow distinction of terrain
on monitors with only 16 colors available.  A key to the reduced colors
is in the ToolBox below each of the terrain icons.  Mines are shown as a
yellow dot centered in terrain squares at 3x3, and are not displayed at
1x1.  Start squares show up as a small red arrow or dot.

The border of the terrain mapping limit rectangle can optionally be
displayed (see the preferences item under the Edit menu below).  The
horizontal and vertical map coordinates are displayed in the floating
ToolBox palette as the mouse is moved across the map window.

Two other display options are ownership of bases and pillboxes, and
special square numbering.  These options, which cannot be enabled
simultaneously, place small numbers over the special squares.  Blue
numbers are used for bases, red numbers for pillboxes, and green numbers
for start squares.

Special square numbering is the logical ordering of these objects in the
map data; it does not have any visible effects on the map.  In the Bolo
information displays, bases and pillboxes are indicated starting with
number 1 in the top-left corner of the displays and continuing
left-right top-to-bottom to number 16 (or to the total number of bases
or PBs).  Bolo itself has two options, pillbox labels and base labels,
that display numbering.  However, the Bolo numbers start with zero
rather than the more conventional one.  Thus, Bolo's pillbox and base
labels will be one less than the numbers displayed in BMAPEdit.

BMAPEdit can also display the range of pillbox shots, according to a
checkbox in the preferences dialog.  There are several important ranges
in Bolo, as follows:  1) the maximum distance a tank can shoot is 6 1⁄2
squares from the tank center, 2) the distance at which a pillbox will
begin shooting at a tank is 8 squares from the center of the pillbox,
and 3) the maximum distance a pillbox shot can travel is 8 1⁄2 squares
from the center of the pillbox.  BMAPEdit displays this last range as a
white circle around pillboxes.

Map windows can be scrolled with the scroll bars, with the 'grabber'
hand that is activated by the pressing the space bar, or with the page
up, page down, home, and help keys on extended keyboards.

5.  Map Drawing
BMAPEdit uses a 'foreground – background' style where the foreground
terrain is defined by the icon selected in the ToolBox, and the
background terrain is selected through a popup menu at the bottom of the
ToolBox (a background terrain popup menu also is located in the
preferences dialog).  All drawing applies the foreground terrain to make
changes, while the background terrain is applied when a selected region
is moved, rotated, reflected, or cleared.

Drawing is done with five basic methods: pencil, line, filling, framing,
and painting.  Of these, filling and framing are performed on regions
defined with the selection tools in the ToolBox (the rectangle, rounded
rectangle, oval, polygon, and lasso tools) by using the corresponding
commands in the Utilities menu.  Pencil drawing, line drawing, and
painting are done by clicking with the respective tools from the
ToolBox.
Important--line drawing, filling, and framing apply the pattern currently
selected in the Patterns menu, where a black pixel in the pattern
changes the terrain in the map squares affected to the foreground, and
white pixels cause no changes.  Many effects can be achieved with the
patterns, including, for example, perfect 'checkerboard' mine fields.
Such a mine field would be laid down through the 50% gray pattern.  When
BMAPEdit is first opened, the pattern defaults to solid black.

Pencil drawing changes individual map squares to the foreground terrain.
 It operates in the traditional 'paint' program style.  As the pencil is
moved across a map, the destination square that would be changed by a
click is highlighted with an open white box (except for magnifications
less than 8x8).  Pencil drawing is also the primary way special
squares--refueling bases, pillboxes, and start squares--are added to a
map.  Filling, framing, painting, and line drawing do not apply to
special squares.  Therefore, selecting the base, pillbox, or start
square icons in the ToolBox automatically selects the pencil tool.
Start squares are added to a map by clicking and dragging the pencil
until the desired direction is indicated.  Note--the direction of
existing start squares can be also changed by clicking and dragging with
the pencil.  Special squares are deleted by clicking them with the
bulldozer tool from the ToolBox.  The bulldozer can also be activated
from the pencil tool by holding the option key down.

Lines are drawn after a line segment has been selected by clicking and
dragging with the line tool.  The line produced is affected by the
current pattern, and its size is determined by the current line size
setting in the preferences dialog.  The line tool can also be used to
make square blocks quickly by selecting an appropriate line size and
clicking on the map without dragging.  Lines drawn in road, water, or
deep water terrain at line size equal to 1 produce a path that is
traversable.  Holding down the option key while dragging a line with the
line tool causes BMAPEdit to make a randomly-walked path with a line
size of 1 (the line size setting in this case is ignored).

Filling is performed by selecting a region with a selection tool (see
the ToolBox discussion below) and choosing the Fill Selection item in
the Utilities menu.  Framing is similar, except that the line width used
is determined by the current line size setting in the preferences
dialog.  Two framing operations are available--either inside the
selection boundary, or outside.

Painting is done by clicking with the paint bucket tool.  The paint
bucket simply changes all the identical terrain squares adjacent to the
click location to the foreground terrain.  It operates in the
traditional 'paint' program style.  If the paint bucket is applied
inside a selected region, painting is clipped to the selection boundary
and will not go outside the boundary.  Painting can also be done with
the random blob tool which works similarly to the paint bucket, but
stops when a small irregular shape is produced, rather than changing all
adjacent identical terrain.  Note--holding the option key down while
clicking with the paint bucket does not change terrain, but rather
selects the region that 'paint' would flow to (see the lasso tool
below).  Holding both the shift and option keys down extends an existing
region selection.

Mines and special squares represent special cases.  Mines can only be
applied to existing swamp, crater, road, forest, rubble, or grass
squares.  Attempting to place mines on any other types of terrain is
ignored.  Start squares can only be placed in deep water.  If other
terrain is subsequently applied to a start square, the start square is
removed.  Also, bases and pillboxes 'float'  --  whatever terrain they
have been placed in, including deep water.  The terrain a base or
pillbox sits on is what a map square becomes when that base or pillbox
is moved during a game (currently, Bolo allows only pillboxes to be
moved).  Note--it is possible to create completely unusable refueling
bases by locating them in deep water, with all adjacent squares also
deep water.  A tank can land at the base and refuel, but because boats
cannot remain in deep water unoccupied, there is no way to leave the
base without dying in deep water.

Note--Bolo maps are currently limited to 16 of each type of special
square (bases, pillboxes, and start squares).  BMAPEdit, however, allows
up 32 bases and pillboxes each to be placed on maps.  This is allowed
because it is easy to create more than 16 when copying and pasting
selections.  Rather than automatically eliminating the extras, BMAPEdit
places them and allows you to decide which ones to delete.  This feature
also allows you to examine different options before deciding which is
best.  When saving such a map, however, only the first 16 of each are
put into the map and a dialog appears telling you that the extra bases
and pillboxes were not included.

6.  The ToolBox
The ToolBox is a floating window/palette that is divided into five
sections.  These sections are, from top to bottom:  1) the foreground
terrain selection, 2) current special square counts, 3) the tool
palette, 4) the map coordinate and area of selection display (both in
units of map squares), and 5) the background terrain popup menu.

The foreground terrain selection section is an array of fifteen terrain
types, represented as icons, that can be applied to Bolo maps.  These
icons are identical to the terrain squares as drawn by Bolo in a game.
Just below each icon is a color bar that shows which color is used to
represent that terrain in the reduced color drawing modes (the color
bars do not appear in B&W).  The bottom row of icons in the terrain
palette are the special squares, from left to right, refueling bases,
pillboxes, and start squares.

Clicking the zoom box in the upper right toggles the ToolBox between its
full size and a minimum-sized bar.  Note--the Window Shade function
introduced with System 7.5 performs the same function when double- or
triple-clicking on a window's title bar; they are not entirely
compatible.  Once the ToolBox has been minimized with the zoom box,
Window Shade clicks do not affect it--it must be restored with the zoom
box.

The sixteen tools in the tool palette are described next in
left-to-right, top-to-bottom order.

The pointer tool performs three functions:  dragging selections,
dragging special squares, and double-clicking special squares.  All
dragging is pinned to the terrain limit rectangle which was defined
above, except when Macintosh drag and drop is available.  Moving
selections by dragging them is straightforward, and, after the move, the
terrain in the selection is replaced with the background terrain.  Once
a selection has been dragged, it can be moved again without affecting
the map until the selection is 'set' (or the 'paint has dried') by
selecting another tool, pressing the escape or tab keys, or by switching
to another map window.  See the drag and drop section below for more
information about dragging.

Special squares may be relocated without having to first select them
with one of the selection tools.  Simply click and drag them to the new
location.  Notice that this is different from dragging a selection
because the terrain under the special square is not moved.  Also,
special square drags do not use the Drag Manager (see below) and thus
cannot leave the starting window.

The settings of special squares may be adjusted by double-clicking them.
A double-click brings up a dialog window that will allow you to make
whatever changes you desire.  The special square dialogs are described
in more detail below.

Bases, pillboxes, and start squares are deleted by clicking them with
the bulldozer tool, which is also activated by pressing the option key
while the pencil tool is selected.

The magnifying glass is used to switch display modes.  Holding the
option key down while clicking switches to a lower magnification, while
a normal click produces the opposite effect.  Display modes may also be
switched with the  + and - keys, as well as the number keys.  The
control key functions as a keyboard shortcut for the magnifying glass.

The pencil and line tools are used for pencil and line drawing, as
described above.  Dragging with the shift key down restricts lines to
horizontal, vertical, and diagonal directions.

The random blob and paint bucket tools have been described above in the
drawing section.

Rectangle, rounded rectangle, and oval regions are selected with the
next three tools, respectively.  Dragging with the shift key down causes
square and circle regions to be selected, and if the option key was
pressed when the mouse was clicked, the selections expand from the click
location, causing the selection to be centered at this point.  Centered
selections can be an even or odd number of squares wide and high,
depending on the where the initial click is relative to the center of
the square.  Option-clicks near the center produce odd width and height
selections, otherwise the selection is even number of squares wide and
high.

Polygons are selected with the polygon tool.  Each mouse click in
succession adds another point to the polygon, up to a maximum of 128
points.  A double-click adds a final point and closes the polygon.  The
previous polygon point can be deleted, before the final point is added,
by holding the option key down and clicking.  Note that a polygon does
not have to be open, i.e. a series of points can be closed by 'doubling
back' to the first point.  The sequence of line segments produced can be
framed, but not filled.

The lasso is used to select regions of existing terrain.  Terrain to be
selected is surrounded by a series of points in a manner identical to
polygon selections (the final point is added with a double-click).  The
selection is then shrunk to an outline of terrain dissimilar to the
terrain at the first point selected.

Selections can rotated or reflected perpendicular to a line with the
rotator and reflector transformation tools.  The original selection
region is replaced with the background terrain unless the selection is
not yet 'set' (or the 'paint is still wet').  After rotation or
reflection, the selection can be dragged into final position without
disturbing existing terrain until the selection is 'set'.  Note that it
is possible for special squares to be lost during the transformations.
Two adjacent specials can transform to the same square, causing one to
be removed.  Also, in very small selections, i.e. one square, the
transformation can result in loss of the special square, especially at
rotation or reflection angles that are not even multiples of 45°.  Note
that holding the shift key down while clicking with the rotator and
reflector tools constrains the transformation angle to multiples of 45°.

Finally, you can add lettering to maps with the text tool.

7.  Drag and Drop
Introduced with Macintosh System 7.5 was the ability to drag information
between windows, even those of different applications.  BMAPEdit uses
the Drag Manager for dragging map selections, and also accepts
information transferred from other applications.  Thus, it is possible
to drag map pieces, or even entire maps, to other map windows.  Drag and
drop is really an extension of cut and paste, although it operates
independently from the clipboard.

Dragging selections with the drag manager is nearly identical to when it
is absent, except that selection outlines are allowed to leave the
starting window.  The selection outline snaps to map squares until it is
outside of the window, at which point this is no longer possible.

Dragging from map windows--selections dragged out map windows will
contain the map information in three formats, called drag flavors:  1)
BMAPEdit internal map data, 2) text, and 3) Quickdraw picture format
(PICT).  The last two formats are intended for exporting map information
to other applications, while the internal flavor is for transferring
information between BMAPEdit windows (note that the text flavor can be
disabled with a checkbox in the preferences dialog).

There are two drag destinations external to BMAPEdit that are very
useful for map making--the scrapbook and the desktop.  Selections dragged
to the scrapbook will show the picture representation, and will list the
other drag flavors contained.  If the desktop is the final destination
of a drag, the Finder will create a so-called clipping file containing
the drag information.  Double-clicking a clipping file causes the Finder
to display its contents.  Both of these can be used to store often-used
map pieces.

Dragging to map windows--when a map window becomes the destination of a
drag flavor that BMAPEdit can accept, the two-pixel white border around
the map display is highlighted.  BMAPEdit accepts drags of text,
pictures, and its own internal drag flavor.

See the Text Import/Export section for more information about text
translation of map data, and the Edit menu section for details of
importing pictures.

8.  Snap-To-Grid
BMAPEdit has the ability to restrict drawing operations to an invisible
grid.  The grid defaults to the minimum size of one square, but can be
set to larger values with the Grid Size item in the Options menu (see
the Menus section below).  A grid size of three, for example, will force
the cursor to map squares evenly divisible by three, e.g., squares 3, 6,
9, 12, etc.  When dragging selections or special squares, objects are
moved in offsets from the starting locations that are multiples of the
grid size.

The X-Y map coordinate display in the ToolBox snaps to the current grid
setting.

9.  Random Utilities
BMAPEdit has special utilities for adding random features to Bolo maps.
Several of these--random bases & PBs, random maps, random fills, random
frames, make island, maze fill and city fills--are accessed through the
Utilities menu and are discussed below.  Small random shapes or 'blobs'
can be made with the random blob tool, or with the pencil tool and the
shift key pressed.  The random shape only 'grows' on terrain identical
to the click location in a way similar to the paint bucket Random
'walks' or lines can be added with the line tool and option key held
down.

10. Menus
File menu -- The File menu operates on Bolo maps, text files, and picture
files.  Important features of these menu items are described below.

When the Open item in the File menu is selected, and System 7 is
available, BMAPEdit displays a custom open file dialog box.  As map
files are highlighted in the file list, the map data is read from the
file and a small preview of the map is displayed in the left-hand side.
Neither the outer mines nor the start squares are shown.  In B&W, land
is black and water is white, except for bases and PBs, which are white.
This graphical feedback is intended to give visual clues about the file
being opened, as opposed to selecting a file by just the file name.

BMAPEdit performs a validity check on the special squares when an
existing map is opened.  The check detects bases, pillboxes, or starts
that occupy the same squares, and looks values of armor, direction, shot
speed, shells, mines, and ownership are within the limits defined for
Bolo maps.  If problems are found, a dialog box is displayed asking for
permission to correct the problems.  Out of range values are set to
default values, and extra specials in a single square are removed.  If
you change your mind, the Undo command in the Edit menu will reverse all
the corrections.

A warning dialog is displayed when a map that has no start squares is
saved because such a map is not usable as a game map.

If the option key is pressed while selecting the Close or Save items,
all map windows currently open will be closed or saved.

The Open Text/Save as Text items allow importing and exporting Bolo maps
as text files that can viewed without the Bolo application or a map
editor such as BMAPEdit, using a standard set of ASCII characters.  See
the section on text import/export for complete details of the character
set.

Saving a map as a PICT produces a PICT (Quickdraw picture) file that
shows the Bolo map drawn according to the export format selected in the
preference dialog.  Please note that these files can be quite large at
larger magnifications and if color is desired.

The Launch Map item allows you to start a new Bolo game using the top
map window from BMAPEdit.  If the map has not been saved, you will be
asked to save the map before Bolo is launched.

Bolo map files can be printed in B&W to a PostScript printer, or in
color/grayscale to PostScript Level 2 printer, according to the settings
in the LaserWriter print dialog window.  The output is intended as a
navigational aid, and larger maps are printed with progressively smaller
squares.  Color/grayscale printing will require significantly more time
to print than B&W, and will cause a PostScript error if the printer
selected in the Chooser is not a PostScript Level 2 printer.

Edit menu -- The Edit menu follows the standard Macintosh format.  Map
regions that have been copied or cut and then subsequently pasted can be
dragged into final position using the pointer tool.  Map data that is in
the clipboard is converted to a PICT image according to the export
format selected in the preferences dialog, for export to other
applications.  If auto conversion item in the preferences dialog is
checked, clipboard data is converted to PICT format automatically
whenever BMAPEdit is switched to the background, or when Quit is
selected in the File menu.  If automatic conversion is not enabled (the
default setting), clipboard data can always be converted with the
Convert Clipboard item.  Note--large selections can consume large amounts
of memory, especially when color conversion is requested.  It is
therefore possible for the conversion to fail if not enough memory is
available.

PICT images that are in the clipboard can be pasted into a map.  Terrain
is determined by the colors in the image, and should correspond to the
color bars in the ToolBox.  Red and yellow should be avoided as these
are used for display of special squares and therefore are converted to
the background terrain.

Select All selects a rectangular area that bounds the entire map while
ignoring deep water.  If the map is empty, the entire editable area is
selected.

The Clone item performs a two-step copy-paste operation that allows a
copy of the selected area to be dragged away while leaving the original
terrain untouched.  Because the pasted selection is directly over the
original, there is no visible change to the map.

The Transform Again item repeats the last move, rotation, or reflection
operation on the current selection.  Thus, if the last operation was a
five-square move, transform again will move whatever is currently
selected by the same offset.  With the combination of clone and
transform again, it possible to create a large number of identical
items, and is especially useful in making tiles for the tiled random map
generator (see below).  To do this, draw the first tile, select the
tile, clone it, then drag it to the next position.  Then repeatedly
clone and transform to make a number of tiles.  The command keys
equivalents (cmd-\ and cmd-,) make the process almost instantaneous.

The Preferences item presents a dialog window in which all of the
options for BMAPEdit are selected.  The settings, many of which have
been discussed previously, are preserved in a preferences file.  The
Random Fill % item allows the approximate percentage of a random fill to
be selected.  Random fills are discussed in greater detail below.  The
Show Numbering and Show Ownership checkboxes are mutually exclusive;
they cannot both be checked at the same time.  Another checkbox
determines if text representations of map data are sent when dragging
selection out of BMAPEdit with the Drag Manager (see the drag and drop
section above).  If the Center Map During Save is checked, BMAPEdit will
automatically center the map terrain in the limit rectangle when a map
is saved.

Mag menu -- The Mag menu is used to switch magnification display modes.
Command-key equivalents are provided for convenience.  The
Increase/Decrease items change magnification by one level and can be
accessed through the +/- command keys on the keyboard or keypad.

Patterns menu -- The Patterns menu is used to select the Quickdraw pattern
that is used for line drawing, filling, and framing selections.  It
defaults to solid black, as discussed above.

If you are familiar with editing resources, using ResEdit or other
resource editors, you can edit the patterns provided in BMAPEdit's
resource fork, or add new ones.  The patterns are loaded from resource
type 'PAT#', ID 128.  Editing the solid black pattern, the first one in
the list, is not recommended because without it, there is no way to
perform solid fills and lines.

Utilities menu -- The Utilities menu contains an assortment of operations
that can be performed on Bolo maps.  These operations are now described
in order.

The Fill Selection and Frame Selection items were discussed above in the
Drawing section.

The Random Fill item is used to randomly distribute the foreground
terrain throughout a selection.  The amount of filling will be close to
(but not precisely) the percentage as set in the preferences dialog.
This setting, which is the probability a single square will be filled,
defaults to 20%.  Random fills of boats only affect existing water
terrain (not deep water).  The Random Frame item operates on rectangular
or polygon selections and performs a random walk from point-to-point
using the foreground terrain and a line size of one square.  Also, see
the keyboard shortcuts section for further information about producing
random terrain.

Frame Outside was also discussed above.

The next three items, Make Island, Maze Fill, and City Fill, generate
random fills in selections.  For the maze and city files, if the current
selection is not rectangular, the result is clipped to the selection.

Make Island produces a randomly shaped island inside the selection, and
then performs a fill, random fills, and then a frame as directed.  Popup
menus allow selection of the island and outline terrains, including no
change if desired.  If a polygon is selected, the polygon is used and a
random shape is not produced.  Small, one-square pinholes can be
prevented with a checkbox selection in the Make Island dialog.

The Maze Fill item will produce a random maze in a rectangular area with
one entrance and one exit on opposite sides of the rectangle.  Terrain
for the maze consists of the path terrain and the barrier terrain which
are selected with popup menus in the maze dialog.  Thicknesses of the
paths and barriers are then specified with scroll bars.  The maze
generation algorithm requires an odd number of squares horizontally and
vertically.  If an even number is selected, the maze size will be
decreased by one.

Random cities consisting of horizontal and vertical roads can be
generated with the City Fill item inside of rectangular selections.
Note that parks, consisting mostly of trees, consume a total of four
city blocks each.

The Starter Map item will generate a quick rectangular map filled with
grass and framed with water, and with start squares evenly distributed
about the perimeter.  As an option, starter maps with the original Bolo
map format (104x52) can also be generated.

The Random Map item randomly generates an entire Bolo map, including
special squares if the appropriate checkboxes are selected in the Random
Map dialog.  This utility is very similar to the RandomMapGenerator
written by Peter Lewis (the algorithm was adapted from the source code
for RandomMapGenerator).  Any existing terrain and all special squares
are erased before the map is generated.  The map will be constrained to
whatever region is currently selected, if desired, or a rectangular map
centered in the Bolo grid can be selected as an alternative.  If the
'Deep water inside map' dialog item is not checked, the map region will
be filled with shallow water before the map is generated.  Otherwise,
islands generated will be framed with shallow water.  Pairs of bases can
be linked with roads using the Connect Bases checkbox.  Selecting the In
Pairs checkbox causes an equal number of adjacent bases and pillboxes to
be added in pairs.

Another complete random map utility is the Tiled Random Map, adapted
from Birdman's Map Maker, written by Charles Brabec.  This utility,
which was originally developed to run on Unix computers using standard
console (character) input/output, works by randomly selecting map
pieces, called tiles, from a list of tiles defined in a special kind of
Bolo map, called a tile file.  The tiles, 5x5 map squares in size, are
selected so that the terrain at the center of the edges matches
previously chosen tiles.  Thus, the tiled map generator has the unique
ability to have terrain propagate through a map.  Other unique features
of the tiled map generator include a nonrandom base and pillbox
placement that uses a distribution algorithm, and the six map symmetry
options available, from no symmetry to 4-fold rotational.  A picture
with letters illustrate the current symmetry selection in the tiled map
dialog.  Tiles in tile files that contain terrain not checked among the
allowed terrain checkboxes are rejected for selection, and the default
terrain popup menu selects the terrain that is used to construct blank
tiles.  Blank tiles are created when no tiles can be found in the list
to match existing edges or that fit the checkbox criteria.  Because
there are no checkboxes for mines, boats, or deep water, these terrain
types are always allowed.

Because maps constructed by the tiled map generator are made from the
pieces in a tile file, they are very much a function of the tile file
used.  Tile files consist of rows of 5x5 square map pieces separated by
one square of deep water. Tiles are read from the file one at a time,
starting at the upper left corner and continuing left-to-right,
top-to-bottom, until a tile is encountered that is completely deep sea.
Therefore, normal Bolo maps will not be accepted as tile files because
they will be seen as having no tiles.  Bases and pillboxes on the tiles
are used as hints for selecting locations when placing bases and
pillboxes on the new map. Start squares in tile files, however, are
ignored.

The next five items all operate on special squares.  All the bases,
pillboxes, or start squares can be removed with the Remove Specials
item.  Set To Defaults resets the ownership, armor, etc., values of
bases and pillboxes to the defaults.  The Place Bases & PBs item is used
to add a number of bases and PBs to a selected area, or throughout the
entire map.  A popup menu of placement options allows for symmetrical,
non-symmetrical, or random placement.  Bases and pillboxes are never
added over 'liquid' terrain, i.e. water, deep water, or boats, and
pillboxes are never located on 'solid' terrain, i.e. buildings or shot
buildings.  The function of the In Pairs checkbox is identical to the
similar checkbox in the Random Map dialog.  Similarly, the Place Start
Squares item evenly distributes start squares around a perimeter.
Shuffle Bases & PBs randomly changes the logical order of bases or
pillboxes.  This utility will not have any visible effect on the map,
except for changing the numbers that appear when Bolo's base or pillbox
labels options are selected (see the discussion of map windows above).

The next three items, Clear Mines, Remove Boats, and Replace Terrain,
operate on the entire map, or inside a selected area.  Terrain
replacement allows you to substitute any kind of terrain for another.
If you dislike mines at the beginning of a game they can be removed with
Clear Mines.

Lastly, the Center Terrain utility moves the center of all non-deep
water terrain in the map to the map center, the point 128, 128.  This
facility is provided because the author of Bolo recommends that maps be
centered in the 256x256 point map grid.

Windows menu -- The Windows menu can be used to bring other map windows to
the top, and to show the ToolBox if it has been closed.  The first item,
Center Window, scrolls the top map window so that the center point, 128,
128, is in the center of the window.

11. Custom Map File Icons
A checkbox option in the preference dialog allows BMAPEdit to create
custom file icons when maps are saved.  These icons are 32x32 pixel
images of the map terrain.  Although the icons give graphical hints
about maps, they do have a couple drawbacks.  First, the icons increase
the file size by about 2700 bytes, an amount that can be several times
the size of map files without icons.  Second, in folders with large
numbers of custom icons, the time needed to draw the icons can increase
dramatically because the Finder must read each one separately from the
disk.

Another factor to keep in mind is that a new custom icon may not be
immediately visible.  The Macintosh Finder keeps a cache of information
it needs to draw folder windows, and it can be difficult to get the
Finder to update a window.  The most successful way seems to be to close
and reopen the folder containing the newly-saved map.  If the new
scriptable Finder is available, introduced with System 7.5, BMAPEdit can
tell the Finder to change the icon, in which case the window will be
updated immediately.

If the custom icon option is turned off, BMAPEdit will not create custom
icons for a map file when it is saved, and will remove any existing
icons.  This is because when the map is altered, the icons may not
accurately reflect the new map terrain.

While BMAPEdit can manage custom icons for a single file, it is
impractical to use it for a large number of map files.  Another utility
called Iconz4Maps is available for this purpose.  A copy of Iconz4Maps
is provided with the BMAPEdit distribution package.

12. Special Square Dialogs
These dialogs, which are opened by double-clicking bases, pillboxes, or
start squares with the pointer tool, allow all settings of these special
squares to be selected, including start square direction, initial
ownership, base initial stocks, and pillbox firing intervals.

The pillbox firing interval (or speed) is the number of 20 millisecond
periods between pillbox shots; a 'mad' pillbox fires with a shorter
interval between shots.  Note that the initial firing interval at the
beginning of a game decays rapidly to the idle value of 100.

Ownership is determined by the order in which players join a game, i.e.,
the second player to join would automatically own bases that have been
set to an ownership of 2.

Setting a new base or pillbox number causes two bases or pillboxes to
swap positions--all others are not affected.  If the numbering is
ignored, they are numbered in the order they were placed on the map.
Note that, in the case of pillboxes, this facility is of little use
later in the game because PBs can be killed, moved, and 'replanted'.

The terrain underneath bases and pillboxes can be set in the dialogs.
Also, all existing bases and pillboxes can be set to identical values
with the Set All Pillboxes or Set All Bases buttons (except for
numbering).

13. Keyboard Shortcuts and Actions
Command key:
*   Produces the pointer cursor while pressed

Space bar:
*   Activates the 'grabber' hand for scrolling in map windows

Escape key (also tab key):
*   Deselects any active selection

Shift key:
*   Dragging new selections with the shift key down produces squares,
      square ovals, and circles.
*   Dragging lines and adding polygon points with the shift key down
      restricts lines and new points to horizontal, vertical, and
      diagonal directions.
*   Changes pencil tool to the random blob tool.

Option key:
*   Changes magnifier cursor to demagnifier if demagnification is
      possible.
*   Changes pencil tool to bulldozer for removal of special squares.
*   Clicking and dragging the line tool with the option key pressed
      produces a random walk from the start to the end point.
*   If the option key was pressed when the mouse was clicked while
      dragging a new rectangle, rounded rectangle, or oval selection,
      the new selection expands from the click location, causing the
      selection to be centered at this point.
*   Option-clicking with the polygon tool or the lasso selector causes
      the previous selection point to be replaced.
*   Incrementing or decrementing the magnification level with the
      option key presses causes the magnification change to be centered
      on the center of the map terrain.

Control key:
*   Activates the magnifier cursor for changing map views.

ToolBox keyboard shortcuts:
*   D:               Deep water
*   O:               Deep water (Ocean)
*   W:               Water
*   R:               Road
*   G:               Grass
*   F:               Forest
*   T:               Forest (Trees)
*   L:               Building (waLLs)
*   M:               SwaMp
*   C:               Crater
*   B:               Base
*   P:               Pillbox
*   S:               Start square
*   Arrow keys:      moves to next tool in direction of arrow

Start square dialog shortcuts:
*   Tab:             selects next direction counterclockwise
                     (or anti-clockwise)
*   Option-Tab:      selects next direction clockwise
*   Arrow keys:      selects corresponding cardinal direction
                     (N, S, E, or W)

Additional shortcuts:
*   Delete, clear:   clear selection (same as clear item in Edit menu)

Extended keyboard shortcuts:
*   F1, F2, F3, F4:  corresponding Edit menu operations (undo, cut,
copy, paste)
*   Page Up, Page Down:
                     same as clicking in vertical scroll bar gray
                     areas
*   Help, Home:      same as clicking in horizontal scroll bar gray areas

14. Text Import/Export
Each terrain type is translated to/from an ASCII text character.  These
are intended as a method of illustrating written discussions about
strategy and tactics, especially when posted to the Usenet news groups.
Terrain that has been exported as text will have the proper appearance
when displayed in a mono-spaced font such as Monaco or Courier.  If a
proportionally spaced font is used, map squares in the same vertical
column will not line up.

Several drawbacks with using these characters should be noted.  First,
start squares loose their directionality.  Second, the terrain under
mines is lost, i.e. there is no way to indicate whether a mine is on
grass, swamp, road, rubble, crater, or trees.  Third, for a tank in a
boat, there is no way to tell if it is in water or deep water.  Also,
damage levels to pillboxes cannot be determined.  Finally,
differentiation of ownership of bases and pillboxes for players 4
through 16 is not possible.  None of these will prevent the use of the
character set as intended.  The terrain characters are:
deep water          ;
water               :
swamp               s
grass               blank (space)
road                +
forest              #
crater              c
rubble              r
shot building       %
building            O (not zero)
boat                b
neutral base        @
player 1 base       1
player 2 base       2
player 3 base       3
player 4..16 base   4
neutral pillbox     *
player 1 pillbox    7
player 2 pillbox    8
player 3 pillbox    9
player 4..16 PB     0 (not capital 'O')
visible mine        X
invisible mine      x
start square        S
tank                t
tank in boat        T

Please note that when importing text, all other visible characters are
changed to grass.  Also, the terrain for 'T' is interpreted as either
water or deep water depending on the surrounding map squares.  If the
number of surrounding squares that are deep water is three or less, a
'T' is interpreted as water, otherwise it becomes deep water.  A
carriage return (ASCII control-M) begins a new map row.  When exporting
map terrain as text, all mines are invisible because visibility of mines
is not defined in map files, but rather only while a game is in progress
within Bolo itself.

15. Known Bugs
When dragging selections, quick, rapid, enter and leave movements of the
mouse in and out of the source window can cause the selection outline to
be offset incorrectly.  This is caused by the way dragging is controlled
and can't really be corrected.  Fortunately, it rarely occurs.  Also,
under rare conditions, dragging a selection downward so the window
display scroll can leave lines of old pixels on the screen.  It occurs
so infrequently I have not been able to determine the cause.

16. Warranty
There are no warranties.  The author makes no guarantees that BMAPEdit
will perform as specified, or that its use will not completely ruin your
computer (but it shouldn't, it hasn't ruined his).

17. Epilogue
"For example, consider the rise of hypnocracy during April and May of
1972.  The 43 persons constituting the Grateful Dead's (latest) European
Tour apportioned themselves for the most part between two buses which
came to be known as the Bolo bus and the Bozo bus.  The Bolo bus had a
john in it and its seats faced forward.  The Bozo bus had a refrigerator
and some of its seats were installed facing back, to accommodate four
tables.  And to look back.  The subtle difference in character and
import and atmosphere between the two omnibuses was so profoundly hidden
and enigmatic that you could never possibly understand it.  The Bozos
wore masks, and the Bolos showed their faces.  At one time the Bozos
staged a raid on the Bolo provisions; at one time the Bolo staged a raid
on the Bozo provisions.

"One St. Dilbert defected from the Bozos and lived for a season with the
Bolos.  In view of his subsequent martyrdom, his penitence and
reconciliation with the Bozos, it came to be said that he was a true
hypnocratic missionary to Bololand.  And to look back, it appears
evident that Bozo and Bolo knew themselves each the other's raison
d'etre.  Is hypnocracy not the aspiration to know what it is?"
    --Grateful Dead, Europe '72


"The heavens declare the glory of God;
    the skies proclaim the work of his hands.
"Day after day they pour forth speech;
    night after night they display knowledge.
"There is no speech or language
    where their voice is not heard.
"Their voice goes out into all the earth,
    their words to the ends of the world.
"He determines the number of the stars,
    and calls them each by name.
"Great is our Lord and mighty in power;
    his understanding has no limit."
--Psalm 19:1-4, 147:4, NIV